feat(codelldb): per-platform npm packages as optionalDependencies (esbuild pattern) - #393
Merged
Merged
Conversation
…build pattern) Closes #383. CodeLLDB now ships as five platform packages — @debugmcp/codelldb-{win32-x64,darwin-x64,darwin-arm64,linux-x64,linux-arm64} — declared as optionalDependencies of @debugmcp/mcp-debugger, so npm installs exactly the one matching the host os/cpu. Rust and C/C++ debugging work out of the box on every platform npm serves, and the CLI tarball shrinks from ~54 MB to ~2 MB (it previously bundled linux-x64). - Platform packages are payload shells versioned by the CodeLLDB release (1.11.8): committed manifest/README/LICENSE only, binaries staged at pack time by scripts/stage-codelldb-packages.mjs from the digest-pinned VSIXs (--verify guards against publishing a near-empty package). The win32 package allows cpu arm64 (x64 emulation; no upstream arm64 build). - Resolver: new platform-package candidate probed after the four vendor candidates and before CODELLDB_PATH, via createRequire so it works from the inlined npx bundle; monorepo dev resolution stays vendor-tree-first (codelldb-common deliberately declares no platform-package dependency). - Release: staging + token-first-publish steps in release.yml (guarded by npm-view at the CodeLLDB version, tagged latest explicitly), pack/ provenance lists extended, release-dry-run checks the five against the vendor-manifest pin, sync-versions skips codelldbPlatform-marked packages, prepare-pack resolves optionalDependencies. - Tests: resolver candidate-order coverage, package.json drift guards, plain-node hermeticity probe, self-gating rust npx smoke (arms after first publish), npm install -g retry with --omit=optional in the npx harness for the pre-publish window. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
…idempotency, drift guards
Review follow-ups on the platform-packages PR:
- Resolver precedence: the installed @debugmcp/codelldb-* package is now
the LAST resort — vendor tree, then CODELLDB_PATH, then the package —
so an explicit env override survives the upgrade (three reviewers
flagged the silent shadowing). The require.resolve walk is lazy and
memoized per platform dir; getCodeLLDBVersion reads version.json as a
sibling of the binary it actually resolved before falling back to the
candidate walk (no more cross-install misattribution).
- Release idempotency: the platform-package publish guard distinguishes
E404 from transient npm-view failures ("already exists" is the normal
path at an unchanged pin — a hiccup must not publish over an existing
version and kill the job); the token .npmrc is removed via an EXIT trap;
staging and --verify-only run as separate processes so a silently-dying
vendor process cannot vouch for itself (#389 coupling).
- One source of truth: stage-codelldb-packages.mjs derives platforms and
payload layout from the vendor script's exported PLATFORMS, drops its
duplicate freshness check (downloadAndExtract already has one), stages
in parallel, uses a single failure channel, and extends exec-bit checks
to lldb/bin helpers (warning loudly on a Windows staging host, where
NTFS cannot represent them). sync-versions.cjs now WRITES the
vendor-manifest pin into any workspace package declaring os/cpu — a
CodeLLDB bump is just "edit manifest + DEFAULT_CODELLDB_VERSION, run
sync" — replacing the codelldbPlatform marker field, which is dropped.
- Drift guards: new tests pin release.yml's and release-dry-run.sh's
five-platform lists to SUPPORTED_CODELLDB_PLATFORM_DIRS, assert every
declared os/cpu combo maps back through getCodeLLDBPlatformDir (the
win32-arm64 emulation contract), and forbid an exports map on the
payload shells (it would break the resolver's package.json resolve).
Platform-package READMEs no longer hardcode the CodeLLDB version.
- Test hygiene: the npx install retry now fires only on E404/ETARGET
naming @debugmcp/codelldb-* (any other failure stays loud); the rust
npx smoke imports the real resolver helpers instead of private copies
and timeboxes its collection-time registry probe; dry-run command
substitutions fail as red checklist lines instead of aborting under
set -e; bundle-cli's default is '' (the 'none' sentinel remains as the
explicit escape hatch).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #383. Depends on #392 landing first (the new release step downloads five VSIXs on the runner via the vendor script #392 hardens).
What changed
CodeLLDB now ships as five platform packages —
@debugmcp/codelldb-{win32-x64,darwin-x64,darwin-arm64,linux-x64,linux-arm64}— declared asoptionalDependenciesof@debugmcp/mcp-debugger. npm installs exactly the one matching the host os/cpu (the esbuild pattern), so Rust and C/C++ debugging work out of the box on every platform npm serves, and the CLI tarball shrinks from ~54 MB to ~2.2 MB.Platform packages
scripts/stage-codelldb-packages.mjsfrom the digest-pinned VSIXs (--verifyfails if a package would pack without its binaries — npm silently omits missingfilesentries).sync-versions.cjsskips them via thecodelldbPlatformmarker; a repo release with an unchanged pin skips republishing ~250 MB via the existing npm-view guards.cpu: ["x64","arm64"]— no upstream win32-arm64 build exists, so Windows-on-ARM gets the x64 package (emulation).codelldb-command.ts'sdirname(binary)/../lldbderivations work unchanged.Resolver
New candidate probed after the four vendor-tree candidates and before
CODELLDB_PATH, resolved viacreateRequirefrom codelldb-common (works from the inlined npx bundle; returns null in monorepo dev where the vendor tree wins — codelldb-common deliberately declares no platform-package dependency, drift-guarded).resolveCodeLLDBExecutableSyncImpl/resolveCodeLLDBExecutable/getCodeLLDBVersiongained injectable hooks so the existing candidate-count tests stay hermetic.Release pipeline
release.yml: "Stage CodeLLDB platform packages" step after the build; a dedicated token-first-publish step before the OIDC step (so the five exist before the CLI referencing them goes live), guarded bynpm view @…@$CODELLDB_PKG_VERSION, taggedlatestexplicitly (CodeLLDB-versioned packages are shared across beta/latest channels); pack dry-run + provenance lists extended.prepare-pack.jsnow resolvesoptionalDependencies(the local pack path previously would have shipped literalworkspace:*).release-dry-run.shchecks the five against the vendor-manifest pin + manifest completeness.docs/release-checklist.mddocuments the CodeLLDB bump procedure and the first-publish → trusted-publisher dance.Degraded modes
--omit=optionalinstalls (and the window before first publish): npm ≥11 skips unresolvable optional deps gracefully (verified); the resolver falls through toCODELLDB_PATHwith updated error messages at all six adapter sites. The npx test harness retriesnpm install -gwith--omit=optionalfor older npms.CODELLDB_PATH, untouched).Verification done
stage-codelldb-packages.mjs --verifystaged all 5 locally; git stays clean (payload ignored per-package)optionalDependenciesresolved to concrete1.11.8…\node_modules\@debugmcp\codelldb-win32-x64\adapter\codelldb.exe --liblldb …\lldb\bin\liblldb.dllsync-versions.cjsdry run: five reported "pinned to CodeLLDB 1.11.8 (not synced)", no diffsOnly verifiable at the next release (record for v0.25.0)
Token first-publish of the five (needs
NPM_TOKENstill present), provenance on them, real npm os/cpu selection across platforms, and the npm-view skip-guards on the release after. Afterwards: configure five trusted publishers and move them into the OIDC step (checklist updated).🤖 Generated with Claude Code